/*
 *    DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 *    Copyright (c) [2019] Payara Foundation and/or its affiliates. All rights reserved.
 *
 *    The contents of this file are subject to the terms of either the GNU
 *    General Public License Version 2 only ("GPL") or the Common Development
 *    and Distribution License("CDDL") (collectively, the "License").  You
 *    may not use this file except in compliance with the License.  You can
 *    obtain a copy of the License at
 *    https://github.com/payara/Payara/blob/main/LICENSE.txt
 *    See the License for the specific
 *    language governing permissions and limitations under the License.
 *
 *    When distributing the software, include this License Header Notice in each
 *    file and include the License file at legal/OPEN-SOURCE-LICENSE.txt.
 *
 *    GPL Classpath Exception:
 *    The Payara Foundation designates this particular file as subject to the "Classpath"
 *    exception as provided by the Payara Foundation in the GPL Version 2 section of the License
 *    file that accompanied this code.
 *
 *    Modifications:
 *    If applicable, add the following below the License Header, with the fields
 *    enclosed by brackets [] replaced by your own identifying information:
 *    "Portions Copyright [year] [name of copyright owner]"
 *
 *    Contributor(s):
 *    If you wish your version of this file to be governed by only the CDDL or
 *    only the GPL Version 2, indicate your decision by adding "[Contributor]
 *    elects to include this software in this distribution under the [CDDL or GPL
 *    Version 2] license."  If you don't indicate a single choice of license, a
 *    recipient has the option to distribute your version of this file under
 *    either the CDDL, the GPL Version 2 or to extend the choice of license to
 *    its licensees as provided above.  However, if you add GPL Version 2 code
 *    and therefore, elected the GPL Version 2 license, then the option applies
 *    only if the new code is made subject to such option by the copyright
 *    holder.
 */

package fish.payara.ejb.http.client.adapter;

import javax.naming.Context;
import javax.naming.NamingException;
import java.util.Optional;

/**
 * Adapter for client-side stubs/proxies.
 * <p>In cases when your client side code depends on finer-grained interaction that would be unsuitable for stateless
 * client invocation (for example JMS resources), ClientAdapter allow you to intercept the lookup process and construct
 * client-side wrappers to return instead of direct remote proxy.</p>
 * <p>Adapter is registered in RemoteEJBContext via property
 * {@value fish.payara.ejb.http.client.RemoteEJBContextFactory#CLIENT_ADAPTER}. The property should refer to an instance
 * of {@code ClientAdapter}. To construct more complex sets of adapters, you can use {@link CompositeClientAdapter} and
 * {@link ClientAdapterCustomizer}</p>.
 *
 * @see fish.payara.ejb.http.client.RemoteEJBContextFactory
 * @see CompositeClientAdapter
 */
public interface ClientAdapter {

    /**
     * Construct local (client-side) proxy if name matches. The method is expected to examing {@code jndiName} being
     * looked up and if it matches adapter's adaptation, construct a local proxy and return it wrapped in an {@code Optional<>}.
     * Otherwise it must return {@code Optional.empty()}.
     * <p>Generated proxy intends calling other remote resources, it may use provided {@code remoteContext}, which
     * refers to instance of {@link fish.payara.ejb.http.client.RemoteEJBContext RemoteEJBContext}. Note that provided
     * instance still applies this ClientAdapter, so it is not possible to wrap a remote object with behavior.</p>
     *
     * @param jndiName jndi name requested for lookup
     * @param remoteContext naming context for remote EJB invocation
     * @return Optional.of(proxy) if adapter provides a proxy for given name, Optional.empty() otherwise
     * @throws NamingException if downstream lookup fails, or other validation doesn't pass
     */
    Optional<Object> makeLocalProxy(String jndiName, Context remoteContext) throws NamingException;

}
